home *** CD-ROM | disk | FTP | other *** search
/ The Very Best of Atari Inside / The Very Best of Atari Inside 1.iso / mint / mnthlp95 / source / d.src next >
C/C++ Source or Header  |  1992-08-04  |  13KB  |  353 lines
  1. screen(capsensitive("Dclosedir"))
  2. NAME
  3.     Dclosedir - close a directory
  4.  
  5. SYNOPSIS
  6.     LONG Dclosedir(LONG dirhandle);
  7.  
  8. DESCRIPTION
  9.     Dclosedir close the directory whose handle (returned from
  10.     Dopendir) is dirhandle.
  11.  
  12. RETURNS
  13.     0 on success
  14.  
  15.     EIHNDL if dirhandle is not valid
  16.  
  17. SEE ALSO
  18.     \#Dopendir\#, \#Dreaddir\#
  19.  
  20. Last change: Oct. 1, 1991\end
  21.  
  22. screen(capsensitive("Dcntl"))
  23. NAME
  24.     Dcntl - perform a file system specific operation on a file
  25.     or directory
  26.  
  27. SYNOPSIS
  28.     #include <filesys.h>
  29.  
  30.     LONG Dcntl(WORD cmd, char *name, LONG arg);
  31.  
  32. DESCRIPTION
  33.     Dcntl performs a file system specific command, given by cmd,
  34.     upon the file or directory specified by name. The exact
  35.     nature of the operation performed depends upon the file sys-
  36.     tem on which name resides. The interpretation of the third
  37.     argument arg depends upon the specific command.
  38.     
  39.     Dcntl commands are:
  40.     
  41.     \link("Dcntl commands")DEV_INSTALL\#
  42.     
  43.     \link("Dcntl commands")DEV_NEWTTY\#
  44.     
  45.     \link("Dcntl commands")DEV_NEWBIOS\#
  46.  
  47. RETURNS
  48.     The value returned depends on the specific operation
  49.     requested and the file system involved. Generally, a 0 or
  50.     positive return value should mean success, and a negative
  51.     one failure. An exception is the value returned by
  52.     DEV_INSTALL, which is either a pointer to a kernel informa-
  53.     tion structure, or NULL on failure.
  54.  
  55. SEE ALSO
  56.     \#Bconmap\#, \#Fcntl\#
  57.  
  58. Last change: Dec. 12, 1991\end
  59.  
  60. screen("Dcntl commands")
  61. The only built-in file system which supports \#Dcntl\# opera-
  62. tions is the device file system U:\\DEV, which understands
  63. the following commands:
  64.  
  65.     DEV_INSTALL
  66.         Installs a new device driver whose name is given by
  67.         name (which must be the complete path and file name,
  68.         e.g. U:\\DEV\\FOO). The device may be accessed only
  69.         through GEMDOS file operations; the BIOS will not be
  70.         aware of it. arg is a pointer to a \link("dev_descr")device descriptor\#
  71.         structure.
  72.  
  73.         If the attempt to install the device is successful,
  74.         Dcntl will return a pointer to a structure with type
  75.         "struct kerinfo" that describes the kernel (see the
  76.         documentation for loadable file systems for more infor-
  77.         mation on this structure). This structure is in pro-
  78.         tected memory and can be accessed only in supervisor
  79.         mode. Moreover, the structure is read only; attempts to
  80.         write to it will produce unpredictable errors. If
  81.         there is not enough memory to install the new device, a
  82.         null pointer will be returned.
  83.  
  84.     DEV_NEWTTY
  85.         Installs a driver for a new BIOS terminal device whose
  86.         name is name (this must be the full path name, e.g.
  87.         U:\\DEV\\BAR). arg is the BIOS device number of this
  88.         device. Note that the BIOS must have been told about
  89.         the device already via the Bconmap system call or some
  90.         similar mechanism; otherwise, any attempt to access the
  91.         file will result in an unknown device error (EUNDEV).
  92.         This command simply informs the kernel about a BIOS
  93.         device that already exists, unlike DEV_INSTALL which
  94.         actually creates a new device.
  95.  
  96.     DEV_NEWBIOS
  97.         Installs a driver for a new BIOS non-terminal device
  98.         whose name is name (this must be the full path name,
  99.         e.g. U:\\DEV\\BAR). arg is the BIOS device number of
  100.         this device. Note that the BIOS must have been told
  101.         about the device already via the Bconmap system call or
  102.         some similar mechanism; otherwise, any attempt to
  103.         access the file will result in an unknown device error
  104.         (EUNDEV). Like DEV_NEWTTY, this command informs the
  105.         kernel of the existence of a BIOS device. The differ-
  106.         ence between the two commands is that DEV_NEWTTY should
  107.         be used for devices which may be used as terminal devices 
  108.         (e.g. serial lines), whereas DEV_NEWBIOS is useful for 
  109.         devices for which data must be always transmitted "raw" 
  110.         (e.g. a SCSI tape device, or perhaps a LAN device).
  111.  
  112. Last change: Dec. 12, 1991\end
  113.  
  114. screen("dev_descr")
  115. The device descriptor structure is used in a \link("Dcntl commands")DEV_INSTALL\# 
  116. command in a \#Dcntl\# call.
  117.  
  118. The dev_descr structure is defined in FILESYS.H:
  119.  
  120. struct dev_descr
  121. {
  122.     DEVDRV      *driver;  /* pointer to device driver structure */
  123.     short       dinfo;    /* placed in the "aux" field of file  */
  124.                           /* cookies                            */
  125.     short       flags;    /* either 0 or O_TTY                  */
  126.     struct tty  *tty;     /* if flags & O_TTY, this points to   */
  127.                           /* the tty structure associated with  */
  128.                           /* the device                         */
  129.     long reserved[4];     /* reserved for future expansion -    */
  130.                           /* set to 0                           */
  131. };\end
  132.  
  133. screen(capsensitive("Dlock"))
  134. NAME
  135.     Dlock - lock or unlock a BIOS disk device
  136.  
  137. SYNOPSIS
  138.     LONG Dlock(WORD mode, WORD drv);
  139.  
  140. DESCRIPTION
  141.     Dlock is used to lock or unlock the BIOS device indicated by
  142.     drv. No GEMDOS file operations are permitted on a locked
  143.     drive. Thus, the Dlock call provides a mechanism for disk
  144.     formatters or re-organizers to lock out other processes
  145.     while low-level BIOS or XBIOS operations are in progress on
  146.     the device.
  147.  
  148.     If mode is 1, the drive is locked; if it is 0 then the drive
  149.     is unlocked and may be used again by other programs. If a
  150.     process terminates while holding a lock on a drive, that
  151.     drive is automatically unlocked.
  152.  
  153.     A lock operation followed immediately by an unlock is very
  154.     similar to a media change, except that the lock operation
  155.     will fail if there are open files that refer to the indi-
  156.     cated drive.
  157.  
  158. RETURNS
  159.     0 if the lock/unlock operation was successful
  160.  
  161.     EACCDN if mode is 1 and either open files exist on the drive
  162.     or another process is searching a directory on the drive
  163.     
  164.     ELOCKED if mode is 1 and another process has locked the
  165.     drive
  166.     
  167.     ENSLOCK if mode is 0 and the drive was not locked by this
  168.     process
  169.     
  170.     EDRIVE if drv is not a valid BIOS device number
  171.  
  172. SEE ALSO
  173.     \#Fxattr\#
  174.  
  175. NOTES
  176.     Note that Dlock operates on BIOS devices, which may not
  177.     always be in 1-1 correspondence with GEMDOS drive letters.
  178.     For this reason, to lock GEMDOS drive A: (for example), the
  179.     programmer should call \#Fxattr\# on the root directory of A:
  180.     ("A:\\") and then use the dev field of the structure returned
  181.     in  order to determine the BIOS device corresponding to the
  182.     GEMDOS drive.
  183.  
  184. Last change: Mar. 8, 1992\end
  185.  
  186. screen(capsensitive("Dopendir"))
  187. NAME
  188.     Dopendir - open a directory for reading
  189.  
  190. SYNOPSIS
  191.     LONG Dopendir(char *name, WORD flag);
  192.  
  193. DESCRIPTION
  194.     Dopendir opens the directory whose name is pointed to by
  195.     name for reading. A 32 bit directory handle is returned
  196.     which may be passed to Dreaddir to actually read the direc-
  197.     tory. flag controls the way directory operations are per-
  198.     formed. If flag == 1, then the directory is read in "compa-
  199.     tibility" mode, if flag == 0 then directory operations are
  200.     performed in "normal" mode. In  "compatibility" mode, file
  201.     systems act as if the \#Fsfirst\# and \#Fsnext\# functions were
  202.     being used; in particular, if it is possible file names will
  203.     be restricted to the DOS 8 character name + 3 character
  204.     extension convention, and will be in upper case. In "normal"
  205.     mode, file systems do not attempt to restrict the range of
  206.     names. Moreover, in this mode the \#Dreaddir\# system call
  207.     will also return a file index number (similar to the Unix
  208.     inode number) along with the file name.
  209.  
  210.     New programs should generally use normal mode where possi-
  211.     ble.
  212.  
  213. RETURNS
  214.     A 32 bit directory handle, on success. Note that this handle 
  215.     may be negative, but will never contain the pattern 0xFF
  216.     in the upper byte, whereas all errors do contain this pat-
  217.     tern in the upper byte.
  218.  
  219.     EPTHNF if name is not a valid directory
  220.  
  221.     EACCDN if the directory is not accessible by this program
  222.  
  223.     ENSMEM if the kernel is unable to allocate memory needed for
  224.     the directory operations
  225.  
  226. SEE ALSO
  227.     \#Dclosedir\#, \#Dreaddir\#, \#Drewinddir\#
  228.  
  229. BUGS
  230.     Failure to call Dclosedir() when the search is done could
  231.     result in the system eventually running out of file indices;
  232.     this is fatal. So always call Dclosedir() when you're fin-
  233.     ished with the directory search!
  234.  
  235. Last change: Oct. 1, 1991\end
  236.  
  237. screen(capsensitive("Dpathconf"))
  238. NAME
  239.     Dpathconf - get information about file system configuration
  240.  
  241. SYNOPSIS
  242.     LONG Dpathconf(char *name, WORD mode);
  243.  
  244. DESCRIPTION
  245.     Dpathconf returns information about various limits or capa-
  246.     bilities of the file system containing the file named name.
  247.     The variable mode controls which limit or capability is
  248.     being queried, as follows:
  249.        mode Value Returned
  250.  
  251.        -1   return max. legal value for n in Dpathconf(n)
  252.         0   return internal limit on the number of open files
  253.         1   return max. number of links to a file
  254.         2   return max. length of a full path name
  255.         3   return max. length of an individual file name
  256.         4   return number of bytes that can be written atomically
  257.         5   return information about file name truncation
  258.     If any of these items are unlimited, then 0x7fffffffL is
  259.     returned.
  260.  
  261.     For mode 5, return information about file name truncation,
  262.     the returned value has the following meaning:
  263.  
  264.     0   File names are never truncated; if the file name in any
  265.         system call affecting this directory exceeds the max-
  266.         imum length (returned by mode 3), then the error value
  267.         ERANGE is returned from that system call.
  268.  
  269.     1   File names are automatically truncated to the maximum
  270.         length.
  271.  
  272.     2   File names are truncated according to DOS rules, i.e.
  273.         to a maximum 8 character base name and a maximum 3
  274.         character extension.
  275.  
  276. SEE ALSO
  277.     \#Sysconf\#
  278.  
  279. Last change: Oct. 1, 1991\end
  280.  
  281. screen(capsensitive("Dreaddir"))
  282. NAME
  283.     Dreaddir - read directory information
  284.  
  285. SYNOPSIS
  286.     LONG Dreaddir(WORD len, LONG dirhandle, char *buf);
  287.  
  288. DESCRIPTION
  289.     Dreaddir returns the next file in the directory whose handle
  290.     (from the \#Dopendir\# system call) is dirhandle. The file's
  291.     name and (optionally) a 4 byte index for the file are placed
  292.     in  the buffer pointed to by buf. The file index is omitted
  293.     if the directory was opened in  "compatibility" mode (see
  294.     \#Dopendir\# for details); otherwise, it is placed first in
  295.     the buffer, followed by the (null terminated) name. If two
  296.     names have the same index, then they refer to the same file;
  297.     the converse, however, is not true.
  298.  
  299.     len is the size of the buffer, in total; it should be large
  300.     enough to hold the index (if any), the file name, and the
  301.     trailing 0.
  302.  
  303.     Successive calls to Dreaddir will return all the names in
  304.     the directory, one after another, unless the Drewinddir sys-
  305.     tem call is used to restart the reading at the beginning of
  306.     the directory.
  307.  
  308. RETURNS
  309.     0 if successful
  310.  
  311.     ERANGE if the buffer was not large enough to hold the index
  312.     (if present) and name
  313.  
  314.     ENMFIL if there are no more file names to be read from the
  315.     directory
  316.  
  317. SEE ALSO
  318.     \#Dclosedir\#, \#Dopendir\#, \#Drewinddir\#
  319.  
  320. BUGS
  321.     Failure to call Dclosedir() when the search is done could
  322.     result in the system eventually running out of file indices;
  323.     this is fatal. So always call Dclosedir() when you're fin-
  324.     ished with the directory search!
  325.  
  326. Last change: Oct. 1, 1991\end
  327.  
  328. screen(capsensitive("Drewinddir"))
  329. NAME
  330.     Drewinddir - rewind an open directory
  331.  
  332. SYNOPSIS
  333.     LONG Drewinddir(LONG handle);
  334.  
  335. DESCRIPTION
  336.     Drewinddir rewinds the open directory whose handle (returned
  337.     from the \#Dopendir\# system call) is handle. After the
  338.     Drewinddir call, the next call to \#Dreaddir\# will read the
  339.     first file in the directory.
  340.  
  341. RETURNS
  342.     0 on success
  343.  
  344.     EIHNDL if handle does not refer to a valid open directory
  345.  
  346.     EINVFN if the directory cannot be rewound (for example,
  347.     because of the type of file system on which it is located)
  348.  
  349. SEE ALSO
  350.     \#Dopendir\#, \#Dreaddir\#
  351.  
  352. Last change: Oct. 1, 1991\end
  353.